home *** CD-ROM | disk | FTP | other *** search
/ MacWorld 1998 March / Macworld (1998-03) (Disk 1).dmg / Shareware World / Info / For Developers / DR2.1update5 / README.install < prev    next >
Text File  |  1997-10-23  |  15KB  |  372 lines
  1. October 21, 1997
  2.  
  3. This file describes how to install the individual pieces of the DR2.1update5
  4. MkLinux update.  These pieces are the Microkernel, the Linux Server, the
  5. Default Pager, and the MkLinux Booter.
  6.  
  7. A true DR2.1update5 system also has several RPM (Redhat Package Manager)
  8. packages installed.  These packages were installed during updates 3
  9. and 4.  There are no new RPMs to install for this update, however you
  10. should have the RPMs up through update4.  In case you are not applying
  11. DR2.1update5 directly from DR2.1update4, there are some tips at the
  12. bottom of this file to help you skip updates when bringing your system
  13. up to a full "DR2.1update5" level.
  14.  
  15. How to install the Mach Kernel and Linux Server
  16. -----------------------------------------------
  17.  
  18. Before we go on, there is something that must be said:
  19. ** ALWAYS BE SURE TO MAKE BACKUP COPIES OF THE MACH KERNEL AND LINUX SERVER. **
  20. (especially if you already had MkLinux running, or even limping :-)
  21.  
  22. For the Mach Kernel, which normally lives in your Extensions folder, just
  23. rename the file.  For the Linux Server, vmlinux, be sure to leave a backup
  24. copy in the /mach_servers directory.  If something doesn't work right with
  25. the new kernel/server pair, you'll be able to go back to the old kernel
  26. (by renaming it back to "Mach Kernel" in your extensions folder), boot it
  27. and the previous vmlinux.  You should also save a copy of your previous
  28. MkLinux Booter (in the Extensions folder as well).
  29.  
  30.  
  31. Obtaining the kernel/server pair
  32. --------------------------------
  33.  
  34. The Mach Kernel and Linux Server can be ftp'ed from the MkLinux ftp site:
  35.     ftp://ftp.mklinux.apple.com/pub/Updates/DR2.1update5/
  36.  
  37. The Mach Kernel is gzipped (ie. compressed) and is called:
  38.     Mach_Kernel.gz
  39.  
  40. The Linux Server is also gzipped, and is called:
  41.     vmlinux.gz
  42.  
  43. These files should be available on various mirror sites as well.
  44.  
  45.  
  46. General downloading notes
  47. -------------------------
  48.  
  49. If you are using Mac OS to download files, make sure you set the format
  50. to BINARY for ftp'ing these files.
  51.  
  52. We recommend you use Fetch or similar FTP Mac OS application rather than
  53. Netscape or another Web Browser.  Some browsers are incorrectly configured,
  54. resulting in corrupted downloaded files.  Some browsers will attempt to
  55. display binary files such as the uncompressed Mach Kernel on the screen.
  56.  
  57. A copy of Fetch can be found in ftp://ftp.mklinux.apple.com/pub/FTP_tools
  58.  
  59.  
  60. The Mach Kernel
  61. ---------------
  62.  
  63. We provide a pre-built Mach Kernel in gzipped (compressed) form.  The
  64. file name on the ftp site is:
  65.     Mach_Kernel.gz
  66.  
  67. You will need to "gunzip" it (ie. uncompress it) before it is usable.
  68. Then, it must be placed in your Extensions folder, with the name:
  69.     Mach Kernel
  70.  
  71. Note, there's a space in that name, even though on the ftp site there
  72. is an underscore in the name.  Be sure to rename the file appropriately!
  73.  
  74. Note also that the gunzipped version will look like a simple document:
  75. no fancy icon, no special type or creator ID.  This is OK.  The Mach Kernel
  76. file is a document used by the MkLinux Booter.  It may not look pretty,
  77. but if it has the correct name (Mach Kernel), the right type (Document,
  78. NOT SimpleText Document) and is in the Extensions folder, the Booter will
  79. find it and launch MkLinux.
  80.  
  81. (see below for hints on how to gunzip files in both MacOS and MkLinux, and
  82. for hints on moving files between the Mac Filesystem and the MkLinux
  83. filesystem)
  84.  
  85.  
  86. The Linux Server
  87. ----------------
  88.  
  89. Like the kernel, we provide a pre-built Linux server in gzipped form.
  90. The file is:
  91.     vmlinux.gz
  92.  
  93. It too must be be gunzipped.  The linux server "lives" in your MkLinux
  94. filesystem, in the directory "/mach_servers".  Its name should be
  95.     /mach_servers/vmlinux
  96. when it's installed.  There is probably already a "vmlinux" file there,
  97. so you should probably rename the old one.
  98.  
  99. (see below for hints on how to gunzip files in both MacOS and MkLinux, and
  100. for hints on moving files between the Mac Filesystem and the MkLinux
  101. filesystem)
  102.  
  103.  
  104. The Default Pager
  105. -----------------
  106.  
  107. The Default Pager, like the Linux Server, is a mach task.  Follow the
  108. instructions for the Linux Server above, but the file is "default_pager.gz".
  109.  
  110.  
  111. The MkLinux Booter
  112. ------------------
  113.  
  114. The MkLinux Booter is an extension that goes in your Extensions folder.
  115. We provide the MkLinux Booter in binhexed form.  The file is:
  116.     MkLinux_Booter.hqx
  117.  
  118. Most Mac-based FTP clients can un-binhex it for you after the file is
  119. retrieved.  There are a number of alternative methods of un-binhexing
  120. the file.  Once you have the MkLinux Booter, place the file in your
  121. Extensions Folder.  NOTE: the file must be named "MkLinux Booter" (with
  122. the space and without the quotes).
  123.  
  124. Version Information
  125. -------------------
  126.  
  127. The version of the Mach Kernel and Linux Server installed on the system
  128. may be obtained through two files located in the /proc filesystem. 
  129.  
  130. To see the version string for the Mach Kernel, type:
  131.     cat /proc/osfmach3/version
  132.  
  133. To see the version string for the Linux server, type:
  134.     cat /proc/version
  135.  
  136. The dates in these two version strings should match the date at the top
  137. of this message.
  138.  
  139.  
  140. How to gunzip (ie. uncompress) files
  141. ------------------------------------
  142.  
  143. If you are running MkLinux, there are a couple ways that you can uncompress
  144. a gzipped file.  For instance, if you have vmlinux.gz, and you want
  145. to uncompress it, use the command:
  146.     gunzip vmlinux.gz
  147.  
  148. As an alternative, you could keep the original ".gz" file and use
  149. the command:
  150.     zcat vmlinux.gz > /mach_servers/vmlinux
  151. (for instance)
  152.  
  153.  
  154. If you are running MacOS, get the tool MacGzip from the ftp site:
  155.     ftp://ftp.mklinux.apple.com/pub/FTP_tools
  156.  
  157. Drag a gzipped file (such as Mach_Kernel.gz) onto the MacGzip icon.
  158. MacGzip will recognize it as a gzipped file and uncompress it.
  159.  
  160. Whichever method you use to gunzip the file, if either program "complains"
  161. about corrupt files, you'll most likely need to FTP the file again.
  162.  
  163.  
  164. How to move files between the MkLinux filesystem and the Mac OS volume
  165. ----------------------------------------------------------------------
  166. The following steps are an example of how to transfer the Mach Kernel
  167. from a MkLinux filesystem to a Mac OS volume and how to transfer a
  168. Linux Server from the Mac OS volume to the MkLinux filesystem.
  169.  
  170. All steps are performed under MkLinux and as the user root.
  171.  
  172. 1) "mount" the HFS volume. You will need to know the SCSI ID and
  173.     partition number of the HFS volume where the file is located.
  174.     For example:
  175.     
  176.     hmount /dev/sda3
  177.     
  178.     This will mount SCSI ID 0 (a=0, b=1, c=2, etc), partition 3.
  179.     You can use the disklabel utility to determine which partion
  180.     is your HFS partition:
  181.     
  182.         disklabel /dev/sda
  183.  
  184. 2) Next, change directory to where the file exists, or is to be placed in,
  185.    the HFS volume.  In this example, the file is to be placed in the Extensions
  186.    folder in the System Folder.
  187.       
  188.    hcd ":System Folder:Extensions"
  189.    
  190.    Note, HFSUTILS uses ":", not "/" to separate names in a path.  For
  191.    example, if the file was located in a folder named "MkLinux Downloads"
  192.    within the folder "My Downloads", then the path would look like
  193.    ":My Downloads:MkLinux Downloads" 
  194.           
  195. 3) The last step actually copies the file.
  196.  
  197.    hcopy -r /tmp/Mach_Kernel ":Mach Kernel"
  198.    
  199.     This will copy the file /tmp/Mach_Kernel (note the underscore) to the
  200.     file "Mach Kernel" (note the space) in the Extensions directory in
  201.     the System Folder on the HFS volume.
  202.  
  203. 4) Or, to copy a file _from_ the HFS volume to MkLinux
  204.           
  205.    hcopy -r ":vmlinux.gz" /tmp/vmlinux.gz
  206.    
  207.    This will copy the vmlinux.gz file from the current location to
  208.    vmlinux in the /tmp directory in the MkLinux filesystem.
  209.    
  210. That's it! For more information, read the hfsutils manual page
  211. (man hfsutils)
  212.  
  213.  
  214. File transfer between MkLinux and the Mac OS volume when you can't run MkLinux
  215. ------------------------------------------------------------------------------
  216. ***
  217. *** NOTE: If you use Linux Disks, be sure to get a recent version!
  218. ***       Version 1.0d5 was known to corrupt the MkLinux filesystem
  219. ***
  220.  
  221. Sometimes, you may need to manipulate the MkLinux filesystem from MacOS.
  222. Although it's not likely that you would need to do this to apply this update,
  223. there is a way to move files to and from the MkLinux filesystem when you're
  224. running MacOS.
  225.  
  226. There is a utility called LinuxDisks written by Michel Pollet.  It is
  227. currently under active development, but is quite effective.  For more
  228. information on obtaining LinuxDisks, point your web browser to:
  229.     http://w3.teaser.fr/~mpollet/LinuxDisks/
  230.  
  231. Even though you probably won't need the tool for this update, it is very
  232. handy to have around.
  233.  
  234.  
  235. Problems after Installation
  236. ---------------------------
  237.  
  238. Some users have reported a new update will cause the system to be
  239. "stuck" at the MkLinux Boot splash screen -- the dialog box which
  240. asks if you want to continue to boot into Mac OS or boot into
  241. MkLinux.
  242.  
  243. Here are some suggestions on how to fix this problem -
  244.  
  245. * Verify the Mach Kernel was correctly downloaded. Web Browsers sometimes
  246.   have problems; we recommend you use Fetch. Be sure the BINARY transfer
  247.   mode was set.  Be sure the Kind is "document".
  248.   
  249. * Some 6100's with DOS cards are reported not to boot MkLinux with the
  250.   DOS card running. Try turning the card off. This can be done through its
  251.   control panel.
  252.   
  253. * Try lowering the Disk Cache size under Mac OS to 96KB or less.
  254.   This can be done through the Memory Control Panel. 
  255.   MkLinux booting has been sensitive to the memory usage of Mac OS.
  256.  
  257. * Verify the system is not running RAM Doubler or a similar product. 
  258.   Also, in some configurations, Speed Doubler has been known to
  259.   conflict with the booting process. 
  260.   
  261.  
  262. Reverting back to the previous Mach Kernel and Linux Server
  263. -----------------------------------------------------------
  264.  
  265. In case the new Mach Kernel and/or Linux server breaks more than it fixes,
  266. you can revert back to the previous version (assuming you have made backup
  267. copies).
  268.  
  269. Restoring the Mach Kernel file is easy; simply copy the backed up version
  270. to the Extensions folder - be sure the file is named "Mach Kernel" (note
  271. that there's a space in the name).
  272.  
  273. Restoring the Linux Server, vmlinux, requires a few more steps -
  274.  
  275. 1) Under Mac OS, edit the lilo.conf file to include the line
  276.          mach_options=-a
  277.  
  278.    The lilo.conf file can edited by clicking on the CUSTOM button
  279.    in the MkLinux control panel.
  280.  
  281.    If you already had a mach_options line (for other reasons), put the
  282.    "-a" at the beginning of the line, just after the "=" symbol.  Ie.
  283.     mach_options=-a -m90 video_probe=true bus_speed_hz=44000000
  284.  
  285.    As an alternative to adding "-a" to your mach_options, you can simply
  286.    press "a" on the "splash screen" (the one with the countdown) when you're
  287.    booting MkLinux.
  288.  
  289. 2) Reboot into MkLinux
  290.  
  291. 3) MkLinux should prompt you for a new bootstrap.conf file.
  292.    Simply press <RETURN>.
  293.  
  294. 4) You will be prompted for the default pager. Press <RETURN> again.
  295.  
  296. 5) At this point you should be prompted for vmlinux (Linux Server).
  297.    Here you can make corrections (i.e. use the DELETE key) to edit
  298.    the name to the backed up version of the Linux Server. Press <RETURN>
  299.    to continue booting.
  300.  
  301. 6) The system should boot with the older version.
  302.  
  303. Once the system is up, restore the old vmlinux file as "/mach_servers/vmlinux".
  304. Don't forget to restore the "mach_options" line in the lilo.conf file.
  305.  
  306.  
  307. Some Tips for skipping previous updates
  308. ---------------------------------------
  309.  
  310. If your system isn't completely at DR2.1update4, and you want to bring
  311. it to the update5 level, do not worry.  You do not need to apply all
  312. the previous updates.  What you need to know is that a true DR2.1update5
  313. system has 4 pieces from the DR2.1update5 directory (the MkLinux Booter,
  314. the Mach Kernel, the Linux Server, and the Default Pager), and many
  315. packages based on shared libraries from the DR2.1update4 update.  In
  316. general, you want to get your system running with the new update5 pieces,
  317. then attend to bringing your shared libraries up to the DR2.1update4
  318. level.
  319.  
  320. Here are some quick recipes for bringing systems to the DR2.1update5 level.
  321.  
  322. From a Fresh Install from DR2.1 CD or FTP install to DR2.1update5:
  323. ------------------------------------------------------------------
  324.  
  325. Partition your disk and run the DR2.1 installer as if you were simply
  326. installing DR2.1.  When the installer (the MacOS application) completes,
  327. run the MkLinux control panel at least once (so that the appropriate
  328. Preferences files are put in place).  Then, before you boot into MkLinux,
  329. obtain the new MkLinux Booter and Mach Kernel from DR2.1update5.  Place
  330. these pieces into your Extensions folder, and THEN boot into MkLinux.
  331. Once MkLinux is up and running, obtain the vmlinux and default_pager
  332. from DR2.1update5 and place them in your Mach Servers directory.  Reboot.
  333. Now, follow the "alternate second half of the DR2.1update4" installation --
  334. the shared libraries.  This involves getting the RPMs from the Alternates
  335. directory in the DR2.1update4 directory and the install_shlibs.u2u4 script.
  336. Execute install_shlibs.u2u4, perform the "forcible reboot", and you're
  337. done.
  338.  
  339. From a DR2.1, DR2.1update1, or DR2.1update2 system to DR2.1update5:
  340. -------------------------------------------------------------------
  341.  
  342. Obtain the new MkLinux Booter and Mach Kernel from DR2.1update5.  Place
  343. these pieces into your Extensions folder, and boot into MkLinux.
  344. Once MkLinux is up and running, obtain the vmlinux and default_pager
  345. from DR2.1update5 and place them in your Mach Servers directory.  Reboot.
  346. Now, follow the "alternate second half of the DR2.1update4" installation --
  347. the shared libraries.  This involves getting the RPMs from the Alternates
  348. directory in the DR2.1update4 directory and the install_shlibs.u2u4 script.
  349. Execute install_shlibs.u2u4, perform the "forcible reboot", and you're
  350. done.
  351.  
  352. From a DR2.1update3 system to DR2.1update5:
  353. -------------------------------------------
  354.  
  355. Obtain the new MkLinux Booter and Mach Kernel from DR2.1update5.  Place
  356. these pieces into your Extensions folder, and boot into MkLinux.
  357. Once MkLinux is up and running, obtain the vmlinux and default_pager
  358. from DR2.1update5 and place them in your Mach Servers directory.  Reboot.
  359. Now, follow the regular "second half of the DR2.1update4" installation --
  360. the shared libraries.  This involves getting the RPMs from the DR2.1update4
  361. directory and the install_shlibs.u3u4 script.  Execute install_shlibs.u3u4,
  362. perform the "forcible reboot", and you're done.
  363.  
  364. From a DR2.1update4 system to DR2.1update5:
  365. -------------------------------------------
  366. Obtain the new MkLinux Booter and Mach Kernel from DR2.1update5.  Place
  367. these pieces into your Extensions folder, and boot into MkLinux.
  368. Once MkLinux is up and running, obtain the vmlinux and default_pager
  369. from DR2.1update5 and place them in your Mach Servers directory.  Reboot,
  370. and you're done.
  371.  
  372.